hsmadmin.h library reference
The ProtectToolkit-C Software Development Kit (SDK) offers a number of extended API libraries with functionality that is extended to that of the standard PKCS#11 function set.
The following additional features do not form part of the standard PKCS#11 functionality, but are provided by Thales as part of the SafeNet ProtectToolkit-C API within the hsmadmin.h library.
The following functions provide an interface to the HSM’s real-time clock (RTC). This library is used in conjunction with the ctconf utility. The ctconf utility provides the capability to set the access control configuration parameters for the RTC.
This library cannot be used in software emulation mode.
Return codes
The return code of all of the functions in the HSMAdmin Library is the enumerated type HSMADM_RV which can have the following values.
| Return Code | Meaning |
|---|---|
| HSMADM_OK | The operation was successful. |
| HSMADM_BAD_PARAMETER | One or more of the parameters have an invalid value. |
| HSMADM_ADJ_TIME_LIMIT | The delta value passed to the HSMADM_AdjustTime() is too large, and will not be used. |
| HSMADM_ADJ_COUNT_LIMIT | The number of calls made to the HSMADM_AdjustTime() that change the time is too large. The adjustment will not be made. |
| HSMADM_NO_MEMORY | There is not enough memory to complete operation. |
| HSMADM_SYSERR | There was a system error. The operation was not performed. |
Function Descriptions
The functions in the HSMAdmin library are described below.
HSMADM_GetTimeOfDay
Obtains the current time of day from the HSM RTC.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_GetTimeOfDay(unsigned int hsmIndex,HSMADM_TimeVal_t * tv );
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used |
| tv | Address of the variable which is to be initialized with the current time of day. It indicates the time passed since midnight, 1 Jan 1970. This struct contains a field tv_usec, which is the number of microseconds. The HSM real-time clock only has millisecond resolution; therefore, tv_usec is always rounded up to the nearest millisecond HSMADM_TimeVal_t is defined in hsmadmin.h. |
HSMADM_AdjustTime
Either adjust the time, or obtain the current adjustment value.
The parameter, delta, indicates the adjustment to be applied to the HSM RTC. The HSM is only capable of performing Slew Adjustment when updating the real-time clock (RTC). This prevents large (multiple second) negative or positive steps of the current RTC. The RTC has a Slew Adjustment of 1 second for every 10 seconds of elapsed time, hence if the RTC was out by 1000 seconds, it will take approx 10000 seconds (2.7 hours) to match the external time source.
Because Slew Adjustment is the means by which the RTC is updated, the HSM may not have completed making an adjustment requested by a previous HSMADM_AdjustTime call. If there is an adjustment being performed when this function is called, then this adjustment is discarded, and the new adjustment value is used instead.
This function can alternatively be used to obtain the value of the time adjustment that remains to be completed. If the parameter delta is NULL, and oldDelta is a valid pointer, it will return the pending adjustment.
Note
The adjustment value added by this function is discarded if the HSM is restarted or shut down.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_AdjustTime(unsigned int hsmIndex,const HSMADM_TimeVal_t * delta,HSMADM_TimeVal_t * oldDelta );
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used. |
| delta | Amount of adjustment to be made to the RTC. This parameter must be NULL if oldDelta is not NULL. HSMADM_TimeVal_t is defined in hsmadmin.h. |
| oldDelta | Address of the variable that will receive the value of the adjustment that remains to be completed. HSMADM_TimeVal_t is defined in hsmadmin.h. If this parameter is not NULL, delta must be NULL. |
HSMADM_SetRtcStatus
Changes the RTC status.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_SetRtcStatus(unsigned int hsmIndex,HSMADM_RtcStatus_t status );
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used |
| status | New status of the RTC. Possible values of the RTC status are defined in hsmadmin.h and are described below. |
Return codes
| Value | Meaning |
|---|---|
| HSMADM_RTC_UNINITIALIZED | The RTC is not initialized yet. |
| HSMADM_RTC_STAND_ALONE | The RTC is in the stand alone mode. This means that it is completely controlled by the crypto subsystem. In this mode, all cryptographic operations are allowed to use the value of the clock. |
| HSMADM_RTC_MANAGED_UNTRUSTED | The RTC is being controlled by an external program; but the value is not trusted yet. This means certain cryptographic operations are refused access to the RTC because the value is (possibly) incorrect. When the RTC Status is set to this value, the ctconf -t command, which normally is used to set the RTC, cannot be used. |
| HSMADM_RTC_MANAGED_TRUSTED | The RTC is being controlled by an external program, and its value may be trusted. This means that all cryptographic operations are allowed to use the value of the clock. When the RTC Status is set to this value, the ctconf -t command, which normally is used to set the RTC, cannot be used. |
HSMADM_GetRtcStatus
Obtain the HSM RTC status.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_GetRtcStatus(unsigned int hsmIndex,HSMADM_RtcStatus_t* status );
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used. This parameter is only valid if RTC Access Control is enabled. RTC Access Control can be modified via the ctconf utility. |
| status | Address of the variable that will obtain the current status of the RTC. This parameter must not be NULL. Possible values of the RTC status are defined in hsmadmin.h and are described below. |
Return codes
| Value | Meaning |
|---|---|
| HSMADM_RTC_UNINITIALIZED | The RTC is not initialized yet. |
| HSMADM_RTC_STAND_ALONE | The RTC is in the stand alone mode. This means that it is completely controlled by the crypto subsystem. In this mode, all cryptographic operations are allowed to use the value of the clock. |
| HSMADM_RTC_MANAGED_UNTRUSTED | The RTC is being controlled by an external program; but the value is not trusted yet. This means certain cryptographic operations are refused access to the RTC because the value is (possibly) incorrect. When the RTC Status is set to this value, the ctconf -t command, which normally is used to set the RTC, cannot be used. |
| HSMADM_RTC_MANAGED_TRUSTED | The RTC is being controlled by an external program, and its value may be trusted. This means that all cryptographic operations are allowed to use the value of the clock. When the RTC Status is set to this value, the ctconf -t command, which normally is used to set the RTC, cannot be used. |
HSMADM_GetRtcAdjustAmount
Get the effective total amount, in milliseconds, of adjustment made to the RTC using the HSMADM_AdjustTime() function.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_GetRtcAdjustAmount(unsigned int hsmIndex, long *totalMs);
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used. |
| totalMs | Address of the variable that will contain the total amount adjusted. The total amount adjusted is calculated by summing the adjust amounts specified via a valid HSMADM_AdjustTime() call. For instance if two adjustments are made of 20ms and -3ms this parameter should return 17ms. This parameter must not be NULL. This parameter is only valid if RTC Access Control is enabled. RTC Access Control can be modified via the ctconf utility. |
HSMADM_GetRtcAdjustCount
Get the effective count of adjustments made to the RTC using the HSMADM_AdjustTime() function.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_GetRtcAdjustCount(unsigned int hsmIndex, unsigned long *totalCount);
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used. |
| totalCount | Address of the variable that will obtain the total count of adjustments. The total count of adjustments indicates the a count of the number of valid adjustments made via HSMADM_AdjustTime() call. This parameter must not be NULL. This parameter is only valid if RTC Access Control is enabled. RTC Access Control can be modified via the ctconf utility. |
HSMADM_GetHsmUsageLevel
Get the usage level of the HSM as a percentage; that is, the load on the HSM.
Synopsis
#include hsmadmin.h
HSMADM_RV HSMADM_GetHsmUsageLevel (unsigned int hsmIndex,
unsigned long* value
);
| Parameter | Description |
|---|---|
| hsmIndex | Zero-based index of the HSM number to be used. |
| totalCount | Address of the variable that will obtain the value. This parameter must not be NULL. |
